Tech Arsenal 1

home *** CD-ROM | disk | FTP | other *** search

/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / pavt117.zip / PAVT117.DOC < prev next >

Wrap

Text File | 1991-12-23 | 22KB | 496 lines

PAvatar 1.17 Turbo Pascal Avatar level 1 Console Kit Copyright c 1991 Gregory P. Smith Part I. Introduction ======================================= This toolkit represents hundreds of hours of programming that resulted in this fast and accurate product. PAvatar is a Turbo Pascal unit (version 5.5 or later) that can provide your programs with Avatar level 1 console, extended Avatar level 0+ (optional ANSI fallback), ANSI-BBS, and ANSI terminal emulations. This is done with a series of procedural hooks for screen I/O and cursor control. This allows you to use the procedures of your choice, making the unit the most flexible of its type. An added bonus to using this unit is DESQview awareness. This unit contains facilities for detecting DESQview, giving up the time slice, and using DESQview's video buffer. This is especially valuable for communications and bbs type programs that are often run under DESQview. Requirements --------------------------- This unit requires that you are using an IBM compatible computer and have Turbo Pascal 5.5 or later. As I have used OOP for fast and efficient data management within this unit; I regret that I cannot provide a Turbo Pascal 5.0 version of the PAvt1 unit. Memory requirements within a program using PAvatar have been kept to a minimum. Only 3-4k of heap space as well as less than 500 bytes stack space. The actual code itself only requires 16k. Shareware --------------------------- I am distributing this unit under a relaxed shareware concept so as to promote Avatar. You are free to use the compiled unit however you want, as long as I'm given credit for the terminal emulations somewhere in the documentation or in the program itself. Please let me know of any programs that you write using PAvatar so that I can recommend them to others. If you want the source code to this unit it is available for $10 U.S., see the registration form for details. The possible benefits of having source code are described later in this document. Liability --------------------------- To use PAvatar you must first agree that I cannot be held responsible for any damages or problems that occur from its use or misuse. If you do not agree to these terms don't use this unit. Part II. QUICK START ======================================= First off you must install your unit. To do so, copy the appropriate TPU file into your units directory (the TPU's have been renamed to .T55 for TP 5.5 and .T60 for TP 6.0, you must rename yours). Next, copy the demo program PAVTDEMO.PAS into your pascal directory. Type TPC pavtdemo or compile it to disk from the IDE. You now have a utility for displaying AVT/1, AVT/0+, and ANSI files that is DESQview aware. Unless you're a Sysop, you probably don't have lots of .AVT Avatar files. Currently there are not many Avatar editors, but you may use my ANSI to Avatar/0+ converter to create Avatar files. It's found on BBS's as A2AVTnnn.ZIP where nnn is the version number (currently 2.10). When typing level 0 files, be sure to use the /PLUS parameter to indicate that it is not a level 1 file (The differences are described later). Part III. Interface ======================================= Procedures --------------------------- PAvatar is a self sufficient unit in that only two procedures are required to add an Avatar or ANSI terminal to your program. However, there are more than two procedures available so that you can take advantage of many special features of the unit. The procedures and definitions follow. Procedure Parse_AVT1 (ch:char); This is the main procedure of the unit. It takes character ch and parses it according to the status. For instance if you pass it a ^V it would go into the Avatar command mode in which the next character would represent an Avatar command. If it were an Esc and ANSI was enabled, the next character passed to it would be tested for a bracket '[' or a shorter VT52 style ANSI commands. This is the heart of the whole unit. Procedure ResetTerminal (nc,nl:byte); This procedure is used to Reset the Terminal emulation with screen dimensions nc columns and nl lines. It always takes you back to the original mode with AVT/1 active, and ANSI fallback turned off. It has the same effect as issuing a ^V^R to the AVT/1 parser. Procedure SetScreen(nc,nl:byte); Use this procedure when you want to change the size of the terminal screen without resetting everything else as in the ResetTerminal procedure. The only thing this does is re- define all of the Avatar windows to have nc columns and nl lines. Procedure AvtInterp (ch:char); This procedure is called by the Parser to interpret the Avatar codes after DLE's and special considerations have been processed. When in ANSI_Only or AVT/0+ mode you can use this instead of Parse_AVT1. The extra overhead of Parse_AVT1 is so small that using this is usually not worth it. Procedure AvtTTY (ch:char); This procedure is called by the AVT/1 Parser when a character is not part of a control code. It simply writes character ch to the screen following the current Avatar window setup (including flow, insert, direction, etc..). The only characters that it processes are CR, LF, BS, Tab, and Bell. You should not need this procedure, but it's here if you do. Procedure Level0_Simulation (fallbck:boolean); This procedure places the interpreter into an extended AVT/0+ emulation mode. If fallbck is true ANSI fallback will be on. Internally, this procedure re-configures AVT/1's window 0 to have a default color of cyan (3), as well as turning cooked mode off. Using this procedure is more effective than sending the equivalent codes for defining a level 0 simulation in a certain window. Destructive backspaces are also disabled. Procedure ANSI_Only; Use this procedure when you want to place the parser in ANSI Only mode. It is the equivalent of putting the AVT/1 parser to sleep and disabling fallback. This is faster than fallback mode. Procedure AvtSound (note:byte; oct:shortint; dur:byte); This procedure is a shortcut to stuff music into the Avatar sound buffer without having to send the code to the parser. Note represents the musical note in the same method which AVT/1's ^V^S command uses it. That is note is equal to (tone - 'A') * 2 + sharp where tone is somewhere between 'A' and 'G'. Sharp is a 0 or a 1 as the case may be. A pause is generated by a note of 14 or greater. The octave is a signed integer in oct where 0 represents middle octave and 1 the next highest, -1 the next lowest. Dur is the duration in tenths of a second. If two identical notes are queued in a row, they will be played legato so that they run together. Procedure StuffSound (frq,dur:integer); This procedure is called by the above procedure. It is used to place a sound of frq hertz and dur tenths of a second into the Sound buffer. If the buffer is full, it will wait until space is available. Procedure Set_Sound_backg(backg:boolean); All sounds produced by the PAvt unit, including the ^G bell, will be made in the background if backg is set to true. Otherwise they will be made in the foreground, delaying the program until they finish. Sound defaults to the background as that is the preferred method for AVT/1. It is worth noting that with foreground sound the timer interrupt ($1c) is not chained and/or DESQview sound calls are not made. Function DESQview_version: word; This is the first of the DESQview supportive routines in this unit. The DESQview major version number is in the high byte, while the minor version is in the low byte. A zero is returned if DESQview is not loaded. Procedure DV_Pause; This procedure will give up the current time slice if you are in DESQview. It does nothing otherwise. Use this procedure when your program is not doing anything, to give the other programs more processing time. Do not hesitate to use this procedure, it's written in assembler so that it's execution time isn't even measurable. Function ReadKey: char; This is a replacement for the Crt unit's ReadKey that gives up the current DESQview time slice (via DV_Pause) if a key hasn't been pressed. Function In_Command: boolean; Returns a true value if the interpreter is in the middle of processing any Avatar or ANSI command. This is useful to prevent strange displays or invalid commands when aborting displays. Procedure UpdateCursor(x,y:byte); This procedure is used to update the cursor position within the current Avatar window to x,y. If a 0 is passed for x, the cursor will be reset to the correct position stored internally by the parser. Variables --------------------------- There are only a few non-procedural variables that you can use to check or modify the status of the terminal. They are all static variables with defined defaults. ANSI_BBS : boolean = False; Use this variable to decide whether the ANSI portion of the unit will use the "BBS" style. The only differences when this is true are that Esc[2J also homes the cursor and Esc[J acts the same as Esc[2J instead of Esc[0J. DOS's own ANSI.SYS is infamous for processing Esc[2J this way. Fallback : boolean = False; This variable controls whether ANSI fallback will be on during Avatar emulations. It is best not to mess with this variable when using AVT/1 as it is designed primarily for use with AVT/0+. ScrnLines : byte = 25; This variable simply defines the number of lines that you want on your terminal screen. Modifying this variable can produce strange results. It is recommended that you use the SetScreen procedure to define the screen size. ScrnColumns : byte = 80; This variable is the partner of the above one. It defines the number of columns you want on your terminal screen. The same restrictions apply with this variable as on the above. QueryReply : string[80] = 'AVT1, Avatar/1 Console Copr. 1991 Greg Smith. Ver 1.17'+^M; When the Avatar terminal id request is received this is the string that will be returned. The "AVT1," at the beginning is important to the remote terminal. It is used to define the capabilities of the terminal. Everything else is just your own logo or program ID. In level 0+ simulation mode the AVT1 is changed to AVT0. Sound_Stat : byte = 3; This variable is used to control which sounds are produced by the unit. If bit 1 is set then the unit can make sounds. Bit 0 only controls the bell (^G) sound. As you can see, the default is to have all sound enabled. Dest_BS : boolean = True; As the name implies, this variable controls the behavior of the backspace (^H) character. The AVT/1 specifications require a Destructive backspace while the AVT/0 specifications require that it is non-destructive. Constants --------------------------- The following constants are available for general use. Esc = ^[; DLE = ^P; FS = #28; GS = #29; RS = #30; US = #31; SP = #32; { space } User Hooks --------------------------- The interface for this unit has been designed to be as flexible as possible without hindering the performance of the unit. Besides the main procedures and a few variables most of it is procedural hooks. Their definitions follow. The Avatar interpreter does not check for invalid screen coordinates on the hooks that need them. It is important that your hooks check the integrity of the coordinates, otherwise seemingly random lockups can occur when invalid or garbled commands are processed. Query_Hook : ReplyProc = Procedure (S:String); This hook is used for all terminal queries or responses such as the Avatar driver query and the ANSI report cursor position. Usually these replies will be placed in the keyboard buffer or sent out the comm port. In pavtdemo, the hook is left at its null procedure setting as there is no use for it in that type of utility. Note that information passed to this hook should be inserted immediately into the input or output buffer so that it is the next thing to be processed if you wish to comply fully with the AVT/1 specifications. WriteATh : WriteATHookT = Procedure (x,y,a:byte;ch:char); This hook is simple and important. It should write character ch on the screen at location x,y using attribute a. This is the only thing it should do, it should not mess with the cursor or scroll the screen. The coordinates are one based. GotoXYh : GotoXYHookT = Procedure (x,y:byte); This hook is used to set the cursor position. Often this routine will call the Crt unit's GotoXY procedure. It is provided for flexibility and the possibility of using PAvatar in a virtual screen or window. Full checking against ScrnLines and ScrnColumns is performed internally. Scrollh : ScrollHookT = Procedure (dir,x1,y1,x2,y2,n,a:byte); This hook is important to Avatar's power. It scrolls the screen region of (x1,y1)-(x2,y2) n lines in the direction indicated in dir (1=up, 2=down, 3=left, 4=right). The empty area created by the scroll should be filled with blank spaces of color attribute a. Most decent windowing toolkits have a procedure suitable for this. FillAreah : FillHookT = Procedure (x1,y1,x2,y2,a:byte;ch:char); This hook is used to fill the screen region of (x1,y1)-(x2,y2) with character ch in attribute a. If your scrolling procedure doesn't support a fill color for the newly exposed area, this is a good procedure to use for it. GetATh : GetCharHookT = Procedure (x,y:byte;var a:byte;var c:char); This hook is the opposite of the WriteATh hook in that its purpose it to retrieve information from the screen. Variable parameters c and a should be set to the character and attribute at the coordinates of x,y respectively. HighAreah : HighHookT = Procedure (x1,y1,x2,y2,a:byte); Similar to FillAreah, this hook fills an area of the screen. The area defined by (x1,y1)-(x2,y2) should be filled with attribute a, but the characters on the screen should not be modified. Pauseh : PauseHookT = Procedure (tenths:word); The only purpose of this hook is to allow for controlled system pauses. This hook should pause the terminal for tenths tenths of a second. The reason I didn't just use a delay(100) within the unit is for the protection of the user. With avatar, codes could be sent that could conceivable pause the system for several days. It is up to you to add a method of breaking out of a pause such as a key press. FlushInputh : Procedure; This hook has a default effect of zeroing the keyboard buffer. If your program has any internal buffers or communications buffer, you may wish to flush them when this hook is called. The Avatar flush input command calls this hook. The PAvt0 Small Version --------------------------- Now included with the Pavt package is a PAvt0 Small version of the unit. This unit is an AVT/0+ and ANSI-BBS terminal only. It is much faster that the AVT/1 unit as there are no flow and window controls. The primary use for this unit is for BBS door programs which won't be using AVT/1. Overall the code there is 10.5k less code and 650 bytes less data as well as a minimal heap usage. Compile the pavtdemo program with the compiler directive of AVT0 for a demo of the PAvt0 unit. The PAvt0 unit is designed as a drop in replacement for the PAvt1 unit. However there are a few procedures and variables which don't exist in the PAvt0 unit. The Pauseh and FlushInputh hooks are not available, the Level0_Simulation, Parse_AVT1, and Set_Sound_backg procedures are not available (AvtInterp should be used instead of Parse_AVT1), and the ANSI_BBS variable is gone. All of these were removed as they served no purpose in AVT/0+. In addition, this unit parses tab characters (^I) as 8 spaces instead of the definable (defaults to 8 char tabs) tab stops of the full unit. Part IV. Special Considerations ======================================= Avatar 1 Console --------------------------- The Avatar level one console is a very powerful terminal emulation. Naturally it goes without saying that there are a few things that must be considered if you wish to comply with the full AVT/1 console specifications. I've already mentioned the need to insert the query replies first into the input or output buffer. Secondly, AVT/1 features a sleep mode for its interpreter, so ANSI fallback should not be used (but it will work); a remote program using level 1 codes should know how to switch between sleeping (ANSI) and awake (AVT/1). The main thing you should be concerned about in communications is flow control. AVT/1 has a way to get around interference with XON/XOFF flow control if the parser is in cooked mode, but if it's switched to raw mode, the results may be disastrous. As AVT/0+ is a raw only terminal, XON/XOFF must be disabled while it is active. Tips & Tricks --------------------------- The AvtInterp procedure is actually a procedural variable that is passed a character as its only parameter. This should let you know a lot about how PAvatar works internally, as well as add flexibility. If you wish to add your own terminal, just assign your own procedures to AvtInterp. This will work when you are calling AvtInterp directly instead of Parse_AVT1. Of course, remember to call the parser when you switch to AVT/1. If your program needs to execute a subprogram or shell to dos there are some special precautions that you must take. You must call the Set_Sound_backg() procedure to restore the timer interrupt. You should also save the exitproc as Set_Sound_backg() only restores it to it's very first state. Here is some sample code for a dos shell: SavedEP := ExitProc; Set_Sound_backg(False); SwapVectors; Exec(GetEnv('COMSPEC''),''); SwapVectors; Set_Sound_backg(True); ExitProc := SavedEP; Part V. History And Credits ======================================= I thank Ping Hansen in the FidoNet pascal echo and an unknown someone in the FidoNet communications echo for sparking my interest in terminal emulations and Avatar. I also would like to thank G. Adam Stanislav for taking on the project of updating the Avatar specification past its original Opus level commands. Last but not least, I would like to thank my parents for putting up with me being on the computer so many hours. Release Sites --------------------------- The following is a list of BBS's where you can find the latest version of PAvatar as well as contacting me. (303)779-4253 The Vault, 300-14400, Fido: 1:104/332 (303)674-1305 Wizardry line 1, 1200-9600. Fido: 1:104/630,631 (303)320-4078 CMOS BBS line 1, 300-9600, Fido: 1:104/441 (303)322-4125 CMOS BBS line 2, 300-9600, Fido: 1:104/469 (303)449-8946 Bohemia BBS Sys, 300-9600, (Unix System) (303)750-7136 Borealis WildCat, 1200-9600, RIME: ->BOREALIS Mark Cook, Sysop of Wizardry, is my only beta tester at this time. I will acquire more as I feel the need. He has unconvered most of the bugs hiding in PAvatar so far. Thanks Mark! --------------------------------------------------------------------- Send all questions, comments, problems, ideas, money, etc.. to: Gregory P. Smith 4422 Pali Way Boulder, CO. 80301 USA Fidonet: 1:104/332,441,477,630,631 RIME: ->BOREALIS UseNet/InterNet: gpsmith@bohemia.metronet.org CompuServe: Route to above internet address.